<% title_tag 'API' %>

<% cache(["api", "v3.10", Date.today]) do %>
<div class="panel panel-default api-doc">
  <div class="panel-heading"><%= Setting.app_name %> - API 目录</div>
  <div class="panel-body markdown">
    <h4>OAuth 2 / API 认证</h4>
    <p>
      在使用 API 之前，你需要 <%= link_to "注册应用", new_oauth_application_path, target: "_blank" %> 并获得可以 OAuth App 信息。并使用标准的 OAuth 2 实现登录，获得 <code>access_token</code> 信息。
    </p>
    <h5>OAuth 路径</h5>
    <ul>
      <li>https://<%= Setting.domain %>/oauth/authorize</li>
      <li>https://<%= Setting.domain %>/oauth/token</li>
      <li>https://<%= Setting.domain %>/oauth/revoke</li>
    </ul>
    <h4>Response 说明</h4>
    <p>所有 Response 采用 JSON 格式返回，请求状态通过 HTTP Status 返回。</p>
    <h5>HTTP Status</h5>
    <ul>
      <li>200, 201 - 请求成功，或执行成功。</li>
      <li>400 - 参数不符合 API 的要求、或者数据格式验证没有通过，请配合 Response Body 里面的 error 信息确定问题。</li>
      <li>401 - 用户认证失败，或缺少认证信息，比如 access_token 过期，或没传，可以尝试用 refresh_token 方式获得新的 access_token。</li>
      <li>403 - 当前用户对资源没有操作权限。</li>
      <li>404 - 资源不存在。</li>
      <li>500 - 服务器异常。</li>
    </ul>
    <p>错误的情况 Response Body 一定会是这样的格式: <code>{ "error" : "Error message" }</code></p>
    <h5>资源权限描述</h5>
    <p>在部分 API 的 response 内容里面你会看到 <code>abilities</code> 节点，这是特别标识当前 access_token 对应的用户对此资源的权限</p>
    <p>请参考源代码，确定那些路径是需要用户认证的，需要用户认证的路径，你需要带上 <code>access_token=?</code> 参数。</p>
    <strong>例如</strong>
    <%= markdown(%(```json
{
  "topic": {
    "id": 256170,
    ....,
    "abilities": { "update": true, "destroy": true }
  }
}
```))%>
    <ul>
      <li><code>update</code> - 是否有权限修改</li>
      <li><code>destroy</code> - 是否有权限删除</li>
    </ul>
    <h4>API 路由</h4>
    <p>下面是简单的 API 路由列表, 具体请参考源代码 <a href="https://github.com/ruby-china/ruby-china/blob/master/app/controllers/api/v3" target="_blank">app/controllers/api/v3</a></p>
    <p>URL 基本路径：<%= request.protocol %><%= Setting.domain %>/api/v3</p>
    <h4>Example</h4>
    <div style="margin-bottom:10px;">
      <p>我们用 Ruby 演示一下访问 /api/v3/hello.json 这个路径，其中包含 OAuth 2 的流程。</p>
      <p>这里用到 RubyGem <a href="https://github.com/intridea/oauth2" target="_blank">oauth2</a>
    </div>
    <%= markdown(%(
```ruby
=> require "oauth2"
=> client = OAuth2::Client.new('client id', 'secret', site: 'https://ruby-china.org')
=> access_token = client.password.get_token('username', 'password')
=> Faraday.get("https://ruby-china.org/api/v3/hello.json?access_token=\#{access_token.token}").body
{ 'current_user' : 'username' }
```
)) %>
  </div>
</div>
<% end %>
